
/*
 * Copyright (C) Igor Sysoev
 * Copyright (C) Nginx, Inc.
 */


#ifndef _NGX_ARRAY_H_INCLUDED_
#define _NGX_ARRAY_H_INCLUDED_


#include <ngx_config.h>
#include <ngx_core.h>


typedef struct
{
    void        *elts;      // 实际数据存储区域.
    ngx_uint_t   nelts;     // 数组元素个数
    size_t       size;      // 数组单个元素的大小，单位是字节
    ngx_uint_t   nalloc;    // 实际不扩容前提下: 最大容量.(可以看作潜力)
    ngx_pool_t  *pool;      // 该数组用来分配内存的内存池.
} ngx_array_t;


ngx_array_t *ngx_array_create(ngx_pool_t *p, ngx_uint_t n, size_t size);
void ngx_array_destroy(ngx_array_t *a);
void *ngx_array_push(ngx_array_t *a);
void *ngx_array_push_n(ngx_array_t *a, ngx_uint_t n);


// be called by ngx_array_create()
// 多个.c源文件中也可以定义同名static 函数, 所以static 函数可以放在头文件中.
static ngx_inline ngx_int_t
ngx_array_init(ngx_array_t *array, ngx_pool_t *pool, ngx_uint_t n, size_t size)
{
    /*
     * set "array->nelts" before "array->elts", otherwise MSVC thinks
     * that "array->nelts" may be used without having been initialized
     */

    array->nelts = 0;       // 逻辑存储元素个数为0
    array->size = size;     // 参数size 是元素的大小.
    array->nalloc = n;      // 参数n 作为不扩容前提下, 最大元素容量.
    array->pool = pool;     // 在pool 内存池中分配内存.


    // 开始在内存池中分配内存.
    array->elts = ngx_palloc(pool, n * size);
    if (array->elts == NULL) {
        return NGX_ERROR;
    }

    return NGX_OK;
}


#endif /* _NGX_ARRAY_H_INCLUDED_ */
